fix(datasource,runtime): declare the guarded optional-driver loads as optional peers - #13401

Fixes #12943

Implements the maintainer's ruling of 2026-08-29 (option 甲, verbatim 「同意」) as one PR across service-datasource and runtime, exactly as that ruling directs.

What changed

Five guarded await import(...) loads of workspace driver packages sat in published src/** with no manifest declaration an installing consumer could see. Each is now an optional peerDependencies entry plus peerDependenciesMeta: { optional: true } — the form @objectstack/cli already uses for driver-turso:

Nothing is installed and no code path changes: an optional peer declares a relationship that already existed at runtime, so npm ls, a lockfile, an audit tool and a reader of the manifest can all see the driver a datasource may ask for, instead of learning about it only by hitting the failure arm. driver-mongodb and driver-sqlite-wasm were devDependencies of service-datasource, which tells a consumer nothing; driver-turso was in no section of either manifest.

⛔ The sixth occurrence of the same shape (rest to objectql, degrading to 501 NOT_IMPLEMENTED) is deliberately untouched: rest's non-coupling to the data engine is a stated architectural position, not a hygiene gap.

The five optional-runtime-probe rows the declarations make stale are deleted from scripts/check-undeclared-dep-imports.mjs — as that gate demands ("once the manifest declares it, the finding is gone and the row is stale, which is RED") and only as far as it demands. ⛔ No row was relaxed to quiet the gate. Of the ledger's 7 rows, 2 remain: rest to objectql, and the unrelated type-only row.

The pin conversions, and a population larger than the card's

pnpm links an optional workspace peer, so a pin that reached its missing-package arm because the package did not resolve stops doing so. The card named one such pin. Measured: there are three, and two of them are in packages/runtime:

⛔ None is deleted or weakened. All three now stage the absence with vi.doMock and the resolver's own ERR_MODULE_NOT_FOUND, keeping every assertion — including the typed-identity ones behind serve.ts's e instanceof MissingDriverPackageError boot-fatality branch.

⭐ vi.doMock without vi.resetModules(), deliberately. A reset re-evaluates missing-driver-package-error.js alongside the factory, so the arm raises a different class object and instanceof is false for a perfectly correct error — measured, in an earlier form of this branch, as expected MissingDriverPackageError … to be an instance of MissingDriverPackageError. Without the reset the identity assertions stay pointed at the binding the host actually holds, which is the only reason they are worth asserting. The two #7385 sibling arms keep using the reset-based raiseWithPackageAbsent helper, untouched — measured, they never relied on the accident, because both their packages already resolve here.

Prose in five places stated the opposite of the new manifests (e.g. *"is not declared by @objectstack/runtime at all"*) and is corrected in runtime/src/turso-driver-factory.ts, service-datasource/src/default-datasource-driver-factory.tsand one comment incli/src/utils/storage-driver.test.ts`.

Verification

Gate family derived at edit time with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (11 paths, never a copied list). Exit codes captured before any pipe. Union re-run on the final commit 69c27808a.

• Full-repo lint — pnpm lint (eslint . --no-inline-config), not a narrowed scan: exit 0.
• Derived gate family, all exit 0: undeclared-dep-imports (+ --self-test), nul-bytes, agent-test-spelling, bash32-floor, changeset-gate-self-tests, cli-command-ids, cross-package-test-inputs, doc-authoring, entry-guard, i18n, i18n-coverage, llms-txt, logger-receiver-detach, objectql-double-limit, objectui-changeset, override-consistency, page-declaration-shape, parse-guard, pm-half-states, pnpm-filter-targets, published-files, slot-lookup, test-source-alias, type-source-resolution, watch-hint-literal, where-matcher, query-options-erasure, engine-double-contract, type-check-coverage, type-check-debt, pm-dispatch-gates, empty-changeset, dual-build-cjs-loads.
  • i18n / i18n-coverage / type-check-debt first answered PREREQUISITE NOT MET ("Nothing was checked") on an unbuilt tree — recorded as NOT MEASURED, never as red — and are green above only after the full closure build turbo run build --filter=./packages/* --filter=./packages/*/*.
  • Gate verdict quoted from the gate itself: ✓ check:undeclared-dep-imports: 78 workspace packages …, 2 ledger row(s), all evidence intact. and check-type-check-coverage --re-measure: OK — 30 ledger entr(ies) re-measured, 1558 raw tsc error(s) total, none above its recorded number. ⛔ No DEBT/TEST_DEBT entry was added or raised.
• Suites: service-datasource 585/585 in 27 files; runtime 2968/2968 in 201 files; cli storage-driver.test.ts 36/36. Typechecks: service-datasource, runtime, cli all exit 0.
  • ⚠️ Declared narrowing, and one honest NOT MEASURED. runtime's tsconfig.json excludes **/*.test.ts, so rt-typecheck green says nothing about the two runtime test files edited here (--listFiles hits: 0). Measured separately with a temporary project that includes them: both files are in the program (hits: 1 each) and zero errors are attributed to either; the 217 errors that program reports are pre-existing residue in runtime's other excluded test files, which is why the exclusion exists and is already ledgered. The probe config was removed and its removal proven (git status clean). For cli only the one edited file was run, its change being a comment.

Reverse verification

Predicted direction, declared before running: with the five rows deleted, removing a declaration can no longer produce a stale-row red — it must produce an unledgered-finding red. Observed exactly that. Dropping driver-turso from service-datasource's peers:

✗ check:undeclared-dep-imports: 1 undeclared workspace import(s)
  • @objectstack/service-datasource <- @objectstack/driver-turso (not declared at all)
      packages/services/service-datasource/src/default-datasource-driver-factory.ts:1239  [dynamic]

The complementary direction was measured too, before the rows were cut: with the declarations landed and the rows still present, the gate named all five as stale and refused. So the deletion is a measured requirement, not an inference.

Ablation — proof the stub still ENTERS the arm (the failure mode that turns a real test into a decoration). Mutating the turso catch in default-datasource-driver-factory.ts to rethrow the raw resolver error turned exactly one test red — the converted pin — on expected '[vitest] There was an error when mock…' to contain 'npm install @objectstack/driver-turso', with the other 49 still passing. Resolution path stated: the test imports its subject by a relative specifier inside the same package, so vitest reads src/*.ts and no rebuild leg applies. Mutation proven on disk (marker count 1, blob 7470571c to 3d275d2b); restore proven by state (blob back to 7470571c, marker count 0, git diff HEAD empty, git status clean), under an EXIT INT TERM trap with absolute paths.

Measured readings that differ from the card

1. ⭐ The card's load-bearing claim is CONFIRMED, against my own prediction. I predicted no link, on the documented ground that auto-install-peers installs missing non-optional peers. pnpm install says otherwise: pnpm-lock.yaml gains link:../../drivers/driver-turso under both importers, and the symlinks exist. Triage had flagged that it never reproduced this; it reproduces.
2. The #7385 siblings do not rely on the accident — they have always staged absence, because their packages already resolve here. The extra work was in packages/runtime instead.
3. runtime's occurrence is the same class: a guarded dynamic import() of an optional package answering with the same typed error. Only the thunk replacement is host-specific.
4. The probe-row count is 6, not 11. LEDGER holds 7 rows, 6 of kind optional-runtime-probe (controls: a nonsense kind returns 0; type-only returns its 1 row). Eleven is the count of text occurrences of the string, which includes the header, LEDGER_KINDS, two diagnostics and a self-test fixture.

One consequence recorded rather than hidden

Declaring the peer adds a workspace edge service-datasource to driver-turso, and driver-turso devDepends on @objectstack/verify to runtime to service-datasource — a cycle. It is invisible to the real build path: turbo's package graph does not read peerDependencies (measured — the 20-task graph for service-datasource#build contains no driver-turso), so pnpm build and CI are unaffected. It is visible to pnpm --filter 'PKG^...', which does read peer edges and now selects a cyclic superset with no topological order. Building through turbo is the workaround used here. Flagged for review rather than decided.

Generated by Claude Code